
########################### HELP - FUNCAO "biomap" - THIAGO F. RODRIGUES 2018 ###############################

biomap               package:unknown                R Documentation

    ESPACIALIZAO E ANLISE DE DADOS DE OCORRNCIA DE ESPCIES


    Description:

    Funo para espacializar e analisar a distribuio de registros de espcies que ocorrem no Brasil,
    alm de identificar potenciais lacunas de conhecimento. A funo fornece um mapa com a distribuio
    de estudos no Brasil, um mapa quantificando os estudos por clula de interesse, um mapa
    quantificando a riqueza de espcies por clula de interesse e uma lista com dois nveis: o
    primero disponibiliza os dados quantificados nos mapas ao usurio e o segundo informa a lacuna de
    conhecimento acerca da distribuio dos estudos no Brasil.

    
    Usage:

    biomap(dados, grid.size=5)

    
    Arguments:

    dados: data.frame com trs colunas na seguinte ordem, obrigatoriamente:
           1 coluna(longitude): a longitude deve estar em graus decimais;
           2 coluna(latitude): a latitude deve estar em graus decimais;
           3 coluna(nome das espcies): nome das espcies.

    grid.size: nmero inteiro no intervalo 1 <= grid.size <= 10 indicando o tamanho das clulas do grid
               em graus de latitude e longitude (p.ex.: '1' indica 1 grau de latitude e longitude ~ 110km)

               
    Details:

    Para que a funo trabalhe corretamente  preciso que A LONGITUDE seja, obrigatoriamente,
    colocada na primeira coluna e A LATITUDE seja, obrigatoriamente, colocada na segunda coluna.
    Assim, a funo gerar os produtos esperados.
    
    As linhas com NAs sero excludas do data.frame.
    
    Caso grid.size no seja definido, a funo padro utiliza tamanho de grid.size = 5.
    
    
    Value:

    Mapa do Brasil com a distribuio das coordenadas geogrficas com escala. (Dispositivo de tela).
    
    Mapa do Brasil com grid definido pelo usurio e quantidade de estudos por clula num gradiente
    de cinza (quanto mais estudos, mais escuro). (Dispositivo de tela).
    
    Mapa do Brasil com grid definido pelo usurio e quantidade de espcies por clula num gradiente
    de cinza (quanto mais espcies, mais escuro). (Dispositivo de tela).
    
    Lista com dois nveis:
        
        -Nvel 1: data.frame(info_map) com cinco colunas contendo informaes extradas dos mapas.
                  As colunas longitude e latitude representam coordenadas geogrficas centrais de cada
                  clula do grid.
        
        -Nvel 2: data.frame(lacuna_de_conhecimento) com cinco colunas contendo a quantidade de clulas
                  com estudo, quantidade de clulas sem estudo, probabilidade da rea coberta com estudo,
                  valor mximo de estudo encontrada e valor mximo de riqueza encontrada.

    A lista gerada tambm ficar disponvel como objeto no "Global Environment" para o usurio
    manipul-la e anlis-la se desejar.
    
                  
    Warning:

    Se algum dos argumentos for inserido incorretamente, a funo no  executada. Com exceo da troca
    de posio entre LONGITUDE E LATITUDE. Neste caso, a funo rodar, mas NO gerar os produtos
    esperados.
    
     necessrio que o usurio esteja conectado  internet, pois a funo faz o download de um
    shapefile do Brasil que fica disponvel de maneira online.
    
    Ao executar a funo,  esperado que ela demore um pouco, pois o procedimento de gerar grid
    demanda um grande processamento da memria do computador.
    
    
    Note:

     necessrio instalar os pacotes "raster" e "sp" antes de utilizar a funo.

    
    Author(s):
    
    Thiago Ferreira Rodrigues - Ecologia Aplicada (ESALQ/USP)
    e-mail: thiagorodriguess@gmail.com 

    
    References:

    BERNARD, E., AGUIAR, L.M.S. & MACHADO, R.B. 2010. Discovering the Brazilian bat fauna:
    a task for two centuries? Mamm. Rev 41: 23-39.
    
    HASUI, E. et al. 2018. ATLANTIC BIRDS: a data set of bird species from the Brazilian Atlantic
    Forest. ECOLOGY 99: 497-497

    
    Examples:
    
    #Lembre-se que  necessrio estar conectado  internet para rodar a funo.
    
    #Exemplo1
    #Neste exemplo, vamos utilizar parte do banco de dados do datapaper publicado na Ecology 2018. 
    #Baixe o arquivo "hasui_et_al_2018_subsetdata.csv" presente no final da pgina principal.
    #Salve o arquivo no seu diretrio de trabalho do R.
    #Importe os dados para seu ambiente de trabalho no R dentro de um objeto chamado "exemplo1".
    exemplo1 <- read.table("hasui_et_al_2018_subsetdata.csv", sep=",", header=TRUE, as.is=TRUE)
    head(exemplo1)
    
    #Leitura da funcao.
    source("biomap.r")
    
    #Roda a funcao 'default'.
    biomap(exemplo1)
    
    #Roda a funcao com diferentes tamanhos de grid.
    biomap(exemplo1, grid.size = 3)
    biomap(exemplo1, grid.size = 7)
        
    
    #Exemplo2 - Se achar mais fcil copie e cole o exemplo abaixo no R       
    # Leitura do pacote necessrio para rodar o exemplo
    library("raster")
    library("sp") 
    
    # Simula 100 coordenadas geograficas dentro do mapa do brasil.
    brasil <- getData('GADM', country='BRA', level=1)
    sim.sp <- spsample(brasil, n = 100, type = "random") 
    
    # Cria data.frame com longitude (lon; repetida 10 vezes), latitude (lat; repetida 10 vezes) e especies (spp; com 1000 nomes e repeticao entre eles)
    exemplo2 <- data.frame(lon=rep(sim.sp@coords[,1], 10), 
                           lat=rep(sim.sp@coords[,2], 10), 
                           spp=paste("sp", sep = "_", sample(LETTERS, 1000, replace = TRUE)))
    
    #Leitura da funcao.
    source("biomap.r")
    
    # Roda a funcao 'default'.
    biomap(exemplo2)
    
    # Roda funcao com diferentes tamanhos de grid.
    biomap(exemplo2, grid.size = 3)
    biomap(exemplo2, grid.size = 7)
    
######################### FIM - HELP - FUNCAO "biomap" - THIAGO F. RODRIGUES #########################
